Land the ui v2 component port on js-toolkit v4 - #642

Move every package that depends on @studiometa/js-toolkit from ^3.9.0 to
^4.0.0-alpha.0, and lift the root override with them. v2 of the ui
packages is built on v4, so the whole workspace has to resolve one major
version.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011izFBQT4AsFcD4tVZz1f7R

Replace the v1 TypeScript sources of 23 component families with the port
written and proved against js-toolkit v4 in the js-toolkit repository, and
drop the families the v2 review drops.

Ported: Action, AnchorNav, Carousel, ClickOutside, Cursor, Data, Dialog,
Draggable, Fetch, Figure, FigureVideo, Hoverable, InView, Indexable, Menu,
Prefetch, Sentinel, Sticky, Timer, Toaster, Track, Transition and
ViewTransition, plus the withTransition mixin the port brought back.

Renamed, per the review: LazyInclude to Defer (directory, class, config
name and its three events, now defer-content, defer-error and
defer-always), AnchorScrollTo to ScrollTo, PrefetchWhenOver to
PrefetchOnInteraction.

Dropped: Accordion (superseded by Disclosure and DisclosureGroup), Frame
(superseded by Fetch), Modal and Panel (superseded by Dialog),
ScrollAnimation with animationScrollWithEase and withScrollAnimationDebug
(superseded by ui-motion), the ImageGrid and Reinsurance templates, the
StyledModal and StyledPanel templates, and the withIndex decorator, whose
whole body is now the Indexable class.

Convert every ported `#private` field and method to the `__` prefix the ui
conventions require, with an `@private` or `@protected` docblock on methods
and getters, and put back the `__abortController`, `__appendSections` and
`__snap` names the port had turned into `protected` keywords.

Rebuild the catalog, the generated manifest and the package exports map
around the v2 surface. A v4 manifest entry is `{ mountStrategy, load }`;
the v3 token, packageName, subpath, exportName, group, children, styles and
integrations fields had no runtime consumer and stay in the authoring
catalog.

Keep the Twig templates of every family the port touches. None of them
needed a rename: their refs (img, video, inner), their options (lazy,
transform, domain, path) and their nested Sentinel all survive the port
unchanged.

Slider is deliberately left on its v1 source: the review calls for a
rewrite onto the Indexable foundation, which is separate work.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011izFBQT4AsFcD4tVZz1f7R

The port keeps its specs beside its sources; in ui they live in
packages/tests, so move all 37 of them there and resolve their imports
through the `#private/*` alias. Delete the v1 specs of the families the
port replaces, and the spec directories of the families v2 drops:
Accordion, Frame, Modal and ScrollAnimation. The v1 Indexable spec goes
with them, because withIndex is gone and the port ships no replacement.

Two harness changes the port forces:

Stage-3 decorators. The ported components declare `@component` and `@on`,
which Oxc, Vite's TypeScript transformer, does not lower, so every file
holding one failed to parse. Compile them with SWC first, behind a filter
that keeps the transform off files with no decorator in them. This is the
same plugin js-toolkit uses for its own suite.

Per-test cleanup. The setup file destroyed every mounted instance through
v3's page-wide `getInstances()`, which v4 removed: instances live on their
element and nothing collects them. Empty the document with `resetDom()`
from `@studiometa/js-toolkit/test` instead, which lets the shared mutation
observer dispose every controller it built.

Point the export-surface specs at families v2 keeps, and read the merged
transition config through `$options` rather than js-toolkit's unpublished
`resolveConfig()`.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011izFBQT4AsFcD4tVZz1f7R

No port existed for this family, so this is the migration itself.

The group/child handshake is gone. v3 answered "which group owns me?" with
`$closest('DisclosureGroup:mounted')` and, because nothing announced a
mount, backed it with a two-way document `CustomEvent` handshake and a
document-wide `MutationObserver` re-running the lookup after any DOM
change. `DisclosureGroup` now holds a live `$watchChildren()` collection
and claims the disclosures below it; a disclosure refuses a claim from a
group further away than its current one, and falls back to the nearest
still-mounted group when its own unmounts. Nesting, mounting in either
order, DOM moves and group teardown all follow from that, with no listener
on `document` and no observer.

`enable()`/`disable()` wrote to `$options` in v3 — the one genuine
reconfiguration in the whole of `@studiometa/ui`, per the port's report.
They now write the presence-only attribute the option reads, and
`optionDisabledChanged()` replaces `updated()` for markup-driven changes.
The other three `$options` writes were state in the wrong place and are
the `isOpen` field.

`config.emits` becomes `$emits`: the disclosure's four events carry no
payload, since v4 hands the emitter over as the event target, and the
group's three carry the item and index v3 passed as extra arguments.
`destroyed()` becomes the cleanup `mounted()` returns, and `nextTick()`
becomes the scheduler's background lane.

The spec is rewritten against the v4 lifecycle: `$destroy()` and
`$update()` no longer exist, so it registers components and drives real
DOM instead of constructing instances by hand.

`reportError()` is polyfilled in the happy-dom setup. It is a platform
global neither Node nor happy-dom provides, js-toolkit's diagnostic
channel calls it as its default error sink, and `$error()` therefore threw
a `ReferenceError` that poisoned the rest of the file.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011izFBQT4AsFcD4tVZz1f7R

No port existed for this family either.

v3 built it on `withMountWhenInView`, and v4 has no decorator to replace.
Its two successors each answer half of what this needs: `mountStrategy:
'visible'` mounts once and never unmounts, `'in-view'` mounts and unmounts
on every crossing — and the `repeat` option chooses between exactly those
two behaviours at runtime, from an attribute, which a static declaration
cannot express. So the component mounts normally and subscribes to
`useInView()`, the core service the strategies are themselves built on.
That also keeps `intersectionObserver` meaningful as the observer's init
rather than a `rootMargin` smuggled into a `data-mount` suffix.

`$terminate()` has no v4 equivalent and needs none: the one-shot guard is a
field, which survives the unmount/mount pair a DOM move now is. The `static
scrollDirectionY` fed by a page-wide `useScroll()` callback registered
under a fixed key and never removed is a per-instance subscription: a v4
service is shared and lazy, and this instance now lives as long as its
element.

`ScrollReveal extends Transition` becomes `withTransition(Base)`, so it no
longer registers under a parent's identity, and the family gets its first
spec.

Two more happy-dom gaps are papered over in the test setup, both of which
break `useScroll()`/`useWindowScroll()` for every family, not just this
one: `window instanceof Window` is false under the global registrator, so
the service cannot tell a window target from an element one, and
`HTMLCollection` has no `Symbol.iterator`, which WebIDL gives it in every
browser.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011izFBQT4AsFcD4tVZz1f7R

Bump `@studiometa/js-toolkit` to `4.0.0-alpha.1` in every package that
declares it and in the workspace override, then refresh the lockfile.
The installed version is checked rather than inferred from the range.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011izFBQT4AsFcD4tVZz1f7R

`4.0.0-alpha.1` exports `SmoothToRecord` from
`@studiometa/js-toolkit/utils`, so the interface copied into `Cursor.ts`
against `4.0.0-alpha.0` is deleted along with the comment explaining it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011izFBQT4AsFcD4tVZz1f7R

Replace happy-dom with Vitest browser mode on Playwright Chromium, the
runner `@studiometa/js-toolkit` proves its own suite with. The components
ask the platform for `IntersectionObserver`, layout geometry, computed
styles and `document.location`, and js-toolkit is entitled to the browser
globals it uses — `reportError()` among them. A DOM emulation answers none
of that, and 167 of the 169 failures were the emulation rather than the
port.

The suite is two projects now. `chromium` runs everything that touches the
DOM. `node` runs the four export-surface specs that read the repository
instead — the TypeScript compiler API, `node:fs`, `node:child_process` —
and cannot run in a page.

The root moves from `packages/` to this package. That is what hung the
previous attempt: `packages/` is harmless as a Node root, but as a Vite
server root it makes the dev server crawl the whole monorepo and the run
never reaches the first test. Dependency discovery is off for the same
class of reason — `ui-motion`, `ui-mapbox` and `Tabs` still import subpaths
v4 removed, and the up-front scan turned one dead subpath into a failure
of the whole run instead of the one spec that owns it.

The three shims that papered over happy-dom breaking platform invariants
(`window instanceof Window`, `HTMLCollection[Symbol.iterator]`,
`reportError`) are gone with the dependency, and so are the `scrollY` and
`requestAnimationFrame` patches beside them. `resetDom()` from
`@studiometa/js-toolkit/test` is the whole teardown.

The helpers a real browser makes pointless go too: `lifecycle.ts` (no
consumer left, and its `destroy()` called the v3-only `$destroy()`),
`resizeWindow.ts` (assigns to the read-only `window.innerWidth`),
`matchMedia.ts` (clobbered a real global for every file importing the
barrel), `mockImageLoad.ts`, `mockVideoLoad.ts`, `faketimers.ts` and
`components.ts` — none had a consumer.

Three specs the new runner exposed are fixed rather than skipped:

- `Disclosure` reports its recovered transition failure on the diagnostic
  channel, whose default sink is `reportError()`. In a browser that becomes
  a global error the runner flags. The spec captures the channel with
  `captureDiagnostics()`, which both asserts the code and suppresses the
  sink.
- The two `dependencies.spec.ts` files reloaded their module singleton with
  `vi.resetModules()`, which cannot clear the page's own module registry.
  A distinct query string is a genuinely distinct module, and still goes
  through Vite's transform so `vi.mock()` still applies.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011izFBQT4AsFcD4tVZz1f7R

`Disclosure` and `DisclosureGroup` both emitted a bare `open` and `close`,
and v4's `$emit()` bubbles, so a listener on the group's element heard its
children too — telling them apart meant reading `event.target` or the shape
of the payload. Both sides take the family prefix `Defer` (`defer-*`) and
`Fetch` (`fetch-*`) already set:

- `Disclosure` emits `disclosure-open`, `disclosure-close`,
  `disclosure-after-open` and `disclosure-after-close`.
- `DisclosureGroup` emits `disclosure-group-open`,
  `disclosure-group-close` and `disclosure-group-change`.

The whole event set of each side is renamed, not only the two that
collided: a half-namespaced family reads as an oversight, and `after-open`
beside `disclosure-open` is the same event vocabulary spelled two ways.
`Disclosure.twig` writes no event name, so it needs no edit; nothing else
in the workspace listens for these.

`export default` comes back on every family's main component. The port had
dropped it across the board, and `subpath-exports.spec.ts` is right to
assert it: `@studiometa/ui/<Component>` has always exposed the main
component both ways. Family members and sub-components keep only their
named export, which is the distinction that spec draws.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011izFBQT4AsFcD4tVZz1f7R

`LargeText` was the last import keeping the `@studiometa/ui` barrel from
loading: it reached for `./withMountWhenInView`, which v4 replaced with the
`data-mount` strategies. `withMountWhenInView(Base, { rootMargin: '50%' })`
is the string `in-view:50%` — the registry owns the observer before any
instance exists, and `data-mount` overrides the margin per element, which v3
could only do by declaring a second class.

The three services v3 bound by the mere presence of `resized()`,
`scrolled()` and `ticked()` are named as three mixins. Two v4 signature
changes are carried rather than worked around: `damp()` takes the elapsed
milliseconds the frame service already delivers, so the same `0.25` factor
now means the same speed on every display; and `transform()` is pure, so the
style write is scheduled explicitly instead of happening inside it. The
template writes no ref, option or event that moved, so it is unchanged. The
generic-API redesign the review asks for is **not** in this commit.

The family gets its first spec: six cases covering the mount strategy, the
measured loop distance, the reversal, the wrap and the optional skew. It
only means anything in a browser, because the loop distance is
`clientWidth`.

With the barrel loading, the four specs that waited on it are unblocked, and
three of them turned out to need splitting. Importing `@studiometa/ui`
registers every component, and registration needs a `MutationObserver`, so a
spec that loads the barrel cannot run under Node at all — while the same
files also asserted `import.meta.resolve`, `node:fs` and a generator run.
The repository half of each moves to its own `*-resolution` /
`*-freshness` file in the Node project; the identity half stays in the
browser. `'$isBase' in X` becomes `X.prototype instanceof Base`, because
v4's brand is a private symbol.

Both export-surface snapshots are regenerated. Every removal is a documented
v2 drop or rename; the additions are the new families, contexts and named
constants — plus sixteen `Data`/`Action` helpers the port exports by name,
which the snapshot now pins for review.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011izFBQT4AsFcD4tVZz1f7R

The v2 barrel snapshot pinned 16 helpers as public API that no consumer
asks for: the `Data` form-control internals (`isCheckbox`, `setProperty`,
`valuesEqual`, `readControlValue`, `writeControlValue`,
`serializeControlValue`, `resolvePropertyName`, `isInput`, `isSelect`),
the two expression compilers (`getCallback`, `compileExpression`), the
event-definition parser, and `getEffect`, `getClosestIndex`,
`resolveDetailPlaceholders` and `resolveDataRegistry`.

They reached the surface because the families export them by name for
each other, and the root barrel re-exported those family barrels whole.

The test for public is documentation plus a dedicated subpath, and it
separates the set cleanly: only `withDeprecation` and `withTransition`
are documented, and they are the only two of the eighteen candidates with
a subpath entry of their own. Both stay. So do the eight named constants
(`FETCH_EVENTS`, `HEADER_NAMES`, `INDEXABLE_BOUNDARIES`, …), which exist
so a no-build-step consumer writes `INDEXABLE_BOUNDARIES.loop` instead of
a bare string.

`CompiledExpression` and `ParsedEventDefinition` go too. Each described
the return of a function that is no longer exported, so keeping them left
a type nothing public could produce.

Nothing was reachable by subpath, so no `exports` entry changes. Every
call site imports relatively and is untouched: the type-error count holds
at 52, all of it in the unported `ui-mapbox`, `ui-motion`, `Tabs` and
`CircularMarquee`, and the suite holds at 3 failed / 571 passed — the
three being `Tabs`, which waits on its rewrite.

Both snapshots are regenerated: `index.spec.ts` loses the 16 runtime
values, and `barrel-exports.spec.ts` those plus the two types.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011izFBQT4AsFcD4tVZz1f7R

**Removed.** `Accordion`, `AccordionItem`, the whole `Frame` family, `Modal`,
`ModalWithTransition`, `StyledModal`, `Panel`, `StyledPanel`, the
`ScrollAnimation` family with `animationScrollWithEase` and
`withScrollAnimationDebug`, `ImageGrid`, `Reinsurance`, `withIndex` and
`AbstractSliderChild` are gone from the package, so their Reference items,
stories and catalog entries go with them.

`viewTransition` follows them for a different reason: core absorbed it, so
`@studiometa/ui/scheduler` no longer exists and the helper is imported from
`@studiometa/js-toolkit`. It was the only documented helper, so the sidebar
stops offering an empty group while the overview page keeps its URL and
explains the absence.

**Renamed.** `LazyInclude` → `Defer` with its `defer-content` /
`defer-error` / `defer-always` events, `AnchorScrollTo` → `ScrollTo`, and
`PrefetchWhenOver` → `PrefetchOnInteraction`. Directories, prose, headings,
stories and catalog ids follow; each page carries the old name as an alias so
search still finds it.

The reference catalog and the public contract list are rebuilt against the
real export surface: 78 stale symbols removed, 48 new ones documented, and
every remaining `related` id and cross-link repointed at a page that still
exists. The sixteen internal helpers the port unexported were never
documented, so nothing referenced them.

`packages/docs/scripts/validate-reference.ts` went from 60 errors to 0, so
`npm run docs:build` reaches the playground build again — where it now stops
on `@studiometa/ui-mapbox` and `@studiometa/ui-motion`, whose unported v3
sources import subpaths js-toolkit v4 removed. Both are left out of the
playground bundle until their ports land; the comment naming the condition is
in `packages/playground/meta.config.js`.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011izFBQT4AsFcD4tVZz1f7R

Every live example is real component code, so the runtime move broke a set of
them in ways a build does not catch. Each fix below was checked in Chromium.

- **`createApp()` is gone from v4.** The four stories that built an app class
  (`Transition`, `ViewTransition`, `Indexable`, `FigureShopify`) register it
  with `registerComponent()` instead, and their markup gains the
  `data-component="App"` root the registry needs. `$children.X[0]` becomes
  `$query('X')[0]`.
- **`registerComponent()` takes one argument.** The second name/selector
  parameter no longer exists, so `registerComponent(ScrollTo, 'a[href^="#"]')`
  registered nothing: the story's links carry `data-component="ScrollTo"` now.
  The alias form — `registerComponent(FigureShopify, 'Figure')` — becomes a
  subclass which declares `name: 'Figure'`, because a component mounts on its
  configured name and the Twig and Liquid templates write `Figure`.
- **`withResponsiveOptions()` is gone; every option is responsive.** The
  responsive mega-menu drops the decorator, and
  `data-option-mode:xxs:xs:s="click"` becomes the v4 cascade —
  `data-option-mode="click"` with `data-option-mode:m="hover"`. `data-breakpoint`
  goes with it.
- **`@component()` registers its class on import.** `Draggable` is one of the
  twenty-one components that do, so the `dynamic-parent` story's subclass was
  refused by the registry and its `parent` override never ran. It is
  `RingDraggable` now, with its own name.
- **`Transition`'s `group` option has no v4 equivalent** — it collected
  siblings from a global instance registry v4 does not keep. The option, the
  `Group` example and its story are removed, and the `FigureShopify` reveal —
  which used `group` to run two transitions as one — drives the overlay it
  contains through `$query()` instead. Its `img` ref was also prefixed for the
  old class name and never resolved.
- **`Slider`'s `center` mode rejects `contain`**, which the center story asked
  for; it warned eleven times per load. The attribute is dropped.
- **The `Defer` error example could not fail.** It fetched `/404`, and
  `fetch()` resolves for any HTTP status, so the component injected the error
  page's markup. It points at an unresolvable `.invalid` host now, and the
  `error` ref finally shows.
- `FigureVideoTwicpics` included the **image** template, so its markup wrote
  `data-component="Figure"` while the script registered `FigureVideo`. It
  includes `@ui/FigureVideo/FigureVideoTwicpics.twig` now.

`Transition`'s JS API also loses `transition-toggle`, which the mixin does not
emit, and gains the array form of `target` and the optional argument on
`enter()` and `leave()`.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011izFBQT4AsFcD4tVZz1f7R

The guide still taught v3's runtime, which the port replaced wholesale.

- **Registering.** `registerComponent()` takes the class and nothing else in
  v4: the alias and CSS-selector second argument is gone, so the guide shows a
  named subclass instead, and notes that twenty-one `@studiometa/ui` classes
  register themselves when their module is imported.
- **`createApp()` does not exist.** "When to use `createApp`" becomes "When to
  use an application component": an app root is an ordinary component with a
  `data-component` on the page root, which is also what scopes its refs.
- **Events bubble**, so the hook section says why each family prefixes its
  event names, and `on<Child><Event>` is documented with the payload v4 hands
  it — `{ target, payload }`.
- **Autoloading was v3 end to end.** `data-load` is `data-mount`, and the four
  strategies are six: `eager`, `visible`, `in-view`, `idle`, `interaction` and
  `media:<query>`, two of them reversible, with the `:<rootMargin>` and
  `:page` suffixes. The `js-toolkit:eager` `<meta>`, `autoload()`,
  `registerManifests()` and the `js-toolkit:error` event are all gone; the
  entry is `registerManifest()` and failures arrive on the
  `js-toolkit:diagnostic` channel with a stable `DIAGNOSTICS` code.

In the Reference, `withMountWhenInView` no longer exists, so the five
components that documented it now name the mount strategy they declare —
`InView` is `in-view`, `InViewOnce` is `visible`, `Figure`, `FigureVideo` and
`AnchorNavTarget` are `in-view`, `LargeText` is `in-view:50%`, `CarouselDrag`
is `media:(pointer: fine)`. `InView` and `InViewOnce` lose their
`intersectionObserver` option with it: the margin belongs to the strategy and
is written as the `data-mount` suffix. `ScrollReveal` keeps its option, and
its page says why — `repeat` picks between the two strategies at runtime, so
it subscribes to the viewport itself.

Every remaining link to the v3 documentation site is repointed at
js-toolkit-v4.studiometa.dev, except in `@studiometa/ui-mapbox`'s pages, whose
sources are still v3.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011izFBQT4AsFcD4tVZz1f7R

`docs:build` does not validate a `twoslash` block. A page importing a symbol
`@studiometa/ui` does not export builds clean, with no error marker and an
empty hover — the transformer is running (the popper markup is in the output)
but every hover it emits is empty and no diagnostic reaches the page.
Twoslash itself is fine: run directly, it reports
`Module '"@studiometa/ui"' has no exported member` for the same snippet. So
the samples below were wrong for as long as the workspace has been on v4 and
nothing said so.

Eight pages still handed the reader `createApp()`, `$children` or the
two-argument `registerComponent()`. `Figure`, `FigureShopify`,
`FigureTwicpics`, `FigureVideo`, `FigureVideoTwicpics` and `ScrollTo` show the
named subclass a renamed `data-component` needs; `Indexable` and `Slider` show
`registerComponent()` with the `data-component="App"` root that scopes an
application component's refs. `Slider`'s two pages drop the subclass entirely:
its optional controls are registered like any other component.

`Toaster` described `Timer` cancelling its countdown from `destroyed()`, which
v4 removed; the cleanup returned by `mounted()` does it.

Every one of the 21 remaining `twoslash` blocks was type-checked by hand
through the twoslasher, and all 21 pass.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011izFBQT4AsFcD4tVZz1f7R

Declare the playback and transition events in the props types now that
`config.emits` is gone, replace `$children.Motion` with live
`$watchChildren()` collections, and move the teardowns off `destroyed()`
— onto the cleanup `mounted()` returns where it pairs with its setup,
onto `unmounted()` where it does not.

`addClass`/`removeClass` do not exist in v4: both were one-line wrappers
over `classList`, so `MotionView` splits its space separated option
value itself, exactly as the ported `ViewTransition` does.

`$warn()` now takes a namespaced diagnostic code, and `$emit()` carries
one named payload object instead of a spread `detail` array — which also
retires `Motion.__dispatch()`, a hand-rolled bubbling `CustomEvent`,
since v4's `$emit()` already bubbles.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011izFBQT4AsFcD4tVZz1f7R

Declare every map event in the props types now that `config.emits` is
gone. A v4 payload is one named object rather than a spread `detail`
array, so the values that used to travel by position are read by name:
`detail.map`, `detail.error`, `detail.items`, `detail.clusterId`.

Drop `withExtraConfig()` from the three controls: it existed because v3
did not merge config along the prototype chain, and v4 does, so each
control is a plain subclass with its own `static config`. The same change
retires the `name`/`debug`/`log` filtering in `AbstractMapboxControl`,
since v4 defines none of those built-in options.

Replace `StoreLocator`'s bounded `nextTick` retry loop — v4 exports no
`nextTick` — and its `MAPBOX_CLUSTER_CONNECTED` subscription with two
`$watchChildren()` collections. Both existed to answer "has the cluster
mounted yet?", which a live collection answers with nothing to poll.
`MAPBOX_CLUSTER_CONNECTED` stays for `MapboxClusterItem`, which looks
*up* for its cluster, and v4 has no watching counterpart to `$closest()`.

`destroyed()` becomes `unmounted()`, and `$warn()` takes a namespaced
diagnostic code — with the contained failures moving to `$error()`,
which carries the cause a warning had nowhere to put.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011izFBQT4AsFcD4tVZz1f7R

The build emits stage-3 decorator syntax verbatim — Oxc does not lower it —
so 21 of the 117 modules in the published `dist/` were unparseable and threw
`SyntaxError` on import, in Node as well as in browsers. Rewrite every
decorator call to its plain equivalent:

- `@component({ … })` becomes `static config`, which also drops the
  `registerComponent(this)` the decorator ran on the side. Registration is now
  the consumer's job for every component in the package, exactly as it already
  was for the 60-odd components that never carried the decorator; the
  autoloader registers each class itself once its manifest entry resolves.
- `@on('click' | 'submit' | 'scroll')` becomes `onClick`, `onSubmit` and
  `onScroll`, and `@on(window, 'popstate')` becomes `onWindowPopstate` — the
  name `FetchShopifySection` already referred to in a docblock.
- `Defer`'s three `@on('defer-content' | 'defer-error')` handlers keep their
  descriptive names and are subscribed from `mounted()`, whose returned
  releases own them: the naming convention cannot spell a hyphenated event.
- `@provide()` becomes `$provide()` and `@children()` becomes
  `$watchChildren()`, matching `Slider` and `Menu`.
- `@write` becomes an explicit `$write()` call around the method body.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011izFBQT4AsFcD4tVZz1f7R

`@rollup/plugin-swc` and `@swc/core` were added only because Oxc cannot lower
stage-3 decorators, and no source in the repository uses one any more —
`packages/ui`, `packages/ui-mapbox`, `packages/ui-motion` and the specs
themselves are all decorator-free, and `@studiometa/js-toolkit` ships built
JavaScript. Vite's own transformer is enough, so the plugin, its filter and
both dependencies go.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011izFBQT4AsFcD4tVZz1f7R

Two pages said some `@studiometa/ui` classes register themselves on import,
because they carried `@component()`. None does now, so the asymmetry a reader
could not see is gone: importing defines a class, registering is what makes it
mount, and the autoloader is the alternative that does both.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011izFBQT4AsFcD4tVZz1f7R

Their v3 sources imported subpaths js-toolkit v4 removed, which is a hard
resolve error for the bundler and failed `docs:build` outright. Both are
ported, so the exclusion — and the comment naming the condition — go with
it. This restores the 32 stories the two packages own.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011izFBQT4AsFcD4tVZz1f7R

`importWhenVisible` and its siblings do not exist in js-toolkit v4:
lazy registration is a manifest entry — a `load` importer plus a
`mountStrategy` the element can override with `data-mount`. Every
lazy-loading section is rewritten around `registerManifest()`, and the
packages' own `./manifest` subpath is named as the shortest way in.

The documented event payloads follow the runtime: a v4 `$emit()` carries
one named object, so `map-load` is `{ map }`, a forwarded mapbox event is
`{ event }`, `map-item-click` is `{ item, feature, event }`, and so on.
Delegated handlers read `{ payload }` rather than v3's `{ args: [...] }`,
and the `Motion`/`Timer` story reads `event.detail.ratio`.

`createApp()` is gone too, so the remaining examples register their
application component like any other, and the prose stops promising a
`$query` retry loop `StoreLocator` no longer runs.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011izFBQT4AsFcD4tVZz1f7R

v4 guarantees no mount ordering and `$watchChildren()` seeds its
collection in a microtask, so `MotionSequence` and `MotionScrollTimeline`
could reach `mounted()` with an empty collection and silently skip the
autoplay or the scroll links. Both now await `whenDOMSettled()` first,
which is the guarantee v3 got for free by having a parent construct its
own children.

`StoreLocator` gains the same correction from the other side: a cluster
that wires before the map has loaded gets a `__refresh()` with no map to
fit or filter against, so the map-load path refreshes unconditionally
rather than only on a first wire.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011izFBQT4AsFcD4tVZz1f7R

`StoreLocator.mounted()` read the `mapboxMap` getter, which warned when
`$query('MapboxMap')` was empty — and v4 mounts a wrapper before the
elements inside it, so every healthy locator reported
`store-locator.no-map` on every page load and recovered silently a moment
later through its `MAPBOX_MAP_CONNECTED` subscription.

The getter no longer warns. A locator with genuinely no map in its markup
is reported once, after `whenDOMSettled()`, and judged on the *element*
rather than the mounted instance: DOM ancestry is a fact that exists
before anything mounts, so the check is immune both to mount ordering and
to the map's mount strategy.

Also corrects the docblocks the port made wrong — the containment routes
to `$error()` now, not `$warn()`, and `destroyed()` is `__onDestroyed()`
— and records why `unmounted()` deliberately keeps `__readyMap`, which an
in-flight `MapboxImage` injection depends on to undo itself.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011izFBQT4AsFcD4tVZz1f7R

Both suites failed at collection, so none of their 226 tests ran. They
are registry-driven now: v3 built a fake `MapboxMap` per test and stubbed
`instance.$closest`, while v4 mounts the real family through
`registerComponents()` and `mount()` and lets each child resolve its own
parent. `MapboxMap/harness.ts` holds what every spec needed — an unloaded
map wrapping given markup, a `load()` that fires `map-load` once the test
has configured the double, and an `append()` that waits for the observer.

The mechanical half: `$destroy()` is `$unmount()`, event payloads are read
by name instead of by position, and `$warn`/console spies become
`captureDiagnostics()`, which reads the channel rather than one of its
sinks.

Two assertions could not survive `config.emits` and are re-expressed
against what the components do. `@studiometa/ui-motion` drives a full
playback lifecycle and asserts the five names it observed. The mapbox
suite pins each component's event set with an exhaustive
`Record<EmitNames<Props>, true>`, so adding or removing an event in the
source is a compile error, and asserts the `map-` prefix at runtime.

Every file keeps its exact test count. Nothing is deleted and nothing is
skipped; the three remaining failures are the deferred `Tabs` rewrite.

`autoload/manifest.spec.ts` was asserting a v3 manifest shape it never
got to run — `token`, `packageName` and `strategy` are gone from a v4
entry — so it now reads `mountStrategy` and checks the loaded class
against the key the registry resolves it by, with `ui-motion` added.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011izFBQT4AsFcD4tVZz1f7R

The default snippet the editor loads still imported and called
`createApp()`, which v4 removed, so every visitor's first playground
session started on a dead API.

`registerComponent()` alone would have been a worse trap. In v4 an
instance exists because its element is in the document *and* its class is
registered, so registering `App` against markup that never declares it
produces a class that mounts nothing, with no error — which is exactly
how the three playground editor subclasses and the 21 self-registering
`@studiometa/ui` components were nearly lost. The default markup now
declares `data-component="App"`.

Verified by loading the default session at /play/ against a locally built
`@studiometa/playground` 0.4.0: the preview iframe completes, the element
carries `data-component="App"`, and the console reports `getDefault
script` with no errors.

The comment about js-toolkit's registry is reworded for the same reason;
it named `createApp` as the thing holding the mutable state.

Note that the site's playground shell stays broken until
`@studiometa/playground` 0.4.0 is released — studiometa/playground#79.
That is a version bump here, not a change to this file.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011izFBQT4AsFcD4tVZz1f7R